home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / cgeesx.z / cgeesx
Text File  |  1996-03-14  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. CCCCGGGGEEEEEEEESSSSXXXX((((3333FFFF))))                                                          CCCCGGGGEEEEEEEESSSSXXXX((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      CGEESX - compute for an N-by-N complex nonsymmetric matrix A, the
  10.      eigenvalues, the Schur form T, and, optionally, the matrix of Schur
  11.      vectors Z
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      SUBROUTINE CGEESX( JOBVS, SORT, SELECT, SENSE, N, A, LDA, SDIM, W, VS,
  15.                         LDVS, RCONDE, RCONDV, WORK, LWORK, RWORK, BWORK, INFO
  16.                         )
  17.  
  18.          CHARACTER      JOBVS, SENSE, SORT
  19.  
  20.          INTEGER        INFO, LDA, LDVS, LWORK, N, SDIM
  21.  
  22.          REAL           RCONDE, RCONDV
  23.  
  24.          LOGICAL        BWORK( * )
  25.  
  26.          REAL           RWORK( * )
  27.  
  28.          COMPLEX        A( LDA, * ), VS( LDVS, * ), W( * ), WORK( * )
  29.  
  30.          LOGICAL        SELECT
  31.  
  32.          EXTERNAL       SELECT
  33.  
  34. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  35.      CGEESX computes for an N-by-N complex nonsymmetric matrix A, the
  36.      eigenvalues, the Schur form T, and, optionally, the matrix of Schur
  37.      vectors Z.  This gives the Schur factorization A = Z*T*(Z**H).
  38.  
  39.      Optionally, it also orders the eigenvalues on the diagonal of the Schur
  40.      form so that selected eigenvalues are at the top left; computes a
  41.      reciprocal condition number for the average of the selected eigenvalues
  42.      (RCONDE); and computes a reciprocal condition number for the right
  43.      invariant subspace corresponding to the selected eigenvalues (RCONDV).
  44.      The leading columns of Z form an orthonormal basis for this invariant
  45.      subspace.
  46.  
  47.      For further explanation of the reciprocal condition numbers RCONDE and
  48.      RCONDV, see Section 4.10 of the LAPACK Users' Guide (where these
  49.      quantities are called s and sep respectively).
  50.  
  51.      A complex matrix is in Schur form if it is upper triangular.
  52.  
  53.  
  54. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  55.      JOBVS   (input) CHARACTER*1
  56.              = 'N': Schur vectors are not computed;
  57.              = 'V': Schur vectors are computed.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CCCCGGGGEEEEEEEESSSSXXXX((((3333FFFF))))                                                          CCCCGGGGEEEEEEEESSSSXXXX((((3333FFFF))))
  71.  
  72.  
  73.  
  74.      SORT    (input) CHARACTER*1
  75.              Specifies whether or not to order the eigenvalues on the diagonal
  76.              of the Schur form.  = 'N': Eigenvalues are not ordered;
  77.              = 'S': Eigenvalues are ordered (see SELECT).
  78.  
  79.      SELECT  (input) LOGICAL FUNCTION of one COMPLEX argument
  80.              SELECT must be declared EXTERNAL in the calling subroutine.  If
  81.              SORT = 'S', SELECT is used to select eigenvalues to order to the
  82.              top left of the Schur form.  If SORT = 'N', SELECT is not
  83.              referenced.  An eigenvalue W(j) is selected if SELECT(W(j)) is
  84.              true.
  85.  
  86.      SENSE   (input) CHARACTER*1
  87.              Determines which reciprocal condition numbers are computed.  =
  88.              'N': None are computed;
  89.              = 'E': Computed for average of selected eigenvalues only;
  90.              = 'V': Computed for selected right invariant subspace only;
  91.              = 'B': Computed for both.  If SENSE = 'E', 'V' or 'B', SORT must
  92.              equal 'S'.
  93.  
  94.      N       (input) INTEGER
  95.              The order of the matrix A. N >= 0.
  96.  
  97.      A       (input/output) COMPLEX array, dimension (LDA, N)
  98.              On entry, the N-by-N matrix A.  On exit, A is overwritten by its
  99.              Schur form T.
  100.  
  101.      LDA     (input) INTEGER
  102.              The leading dimension of the array A.  LDA >= max(1,N).
  103.  
  104.      SDIM    (output) INTEGER
  105.              If SORT = 'N', SDIM = 0.  If SORT = 'S', SDIM = number of
  106.              eigenvalues for which SELECT is true.
  107.  
  108.      W       (output) COMPLEX array, dimension (N)
  109.              W contains the computed eigenvalues, in the same order that they
  110.              appear on the diagonal of the output Schur form T.
  111.  
  112.      VS      (output) COMPLEX array, dimension (LDVS,N)
  113.              If JOBVS = 'V', VS contains the unitary matrix Z of Schur
  114.              vectors.  If JOBVS = 'N', VS is not referenced.
  115.  
  116.      LDVS    (input) INTEGER
  117.              The leading dimension of the array VS.  LDVS >= 1, and if JOBVS =
  118.              'V', LDVS >= N.
  119.  
  120.      RCONDE  (output) REAL
  121.              If SENSE = 'E' or 'B', RCONDE contains the reciprocal condition
  122.              number for the average of the selected eigenvalues.  Not
  123.              referenced if SENSE = 'N' or 'V'.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CCCCGGGGEEEEEEEESSSSXXXX((((3333FFFF))))                                                          CCCCGGGGEEEEEEEESSSSXXXX((((3333FFFF))))
  137.  
  138.  
  139.  
  140.      RCONDV  (output) REAL
  141.              If SENSE = 'V' or 'B', RCONDV contains the reciprocal condition
  142.              number for the selected right invariant subspace.  Not referenced
  143.              if SENSE = 'N' or 'E'.
  144.  
  145.      WORK    (workspace/output) COMPLEX array, dimension (LWORK)
  146.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  147.  
  148.      LWORK   (input) INTEGER
  149.              The dimension of the array WORK.  LWORK >= max(1,2*N).  Also, if
  150.              SENSE = 'E' or 'V' or 'B', LWORK >= 2*SDIM*(N-SDIM), where SDIM
  151.              is the number of selected eigenvalues computed by this routine.
  152.              Note that 2*SDIM*(N-SDIM) <= N*N/2.  For good performance, LWORK
  153.              must generally be larger.
  154.  
  155.      RWORK   (workspace) REAL array, dimension (N)
  156.  
  157.      BWORK   (workspace) LOGICAL array, dimension (N)
  158.              Not referenced if SORT = 'N'.
  159.  
  160.      INFO    (output) INTEGER
  161.              = 0: successful exit
  162.              < 0: if INFO = -i, the i-th argument had an illegal value.
  163.              > 0: if INFO = i, and i is
  164.              <= N: the QR algorithm failed to compute all the
  165.              eigenvalues; elements 1:ILO-1 and i+1:N of W contain those
  166.              eigenvalues which have converged; if JOBVS = 'V', VS contains the
  167.              transformation which reduces A to its partially converged Schur
  168.              form.  = N+1: the eigenvalues could not be reordered because some
  169.              eigenvalues were too close to separate (the problem is very ill-
  170.              conditioned); = N+2: after reordering, roundoff changed values of
  171.              some complex eigenvalues so that leading eigenvalues in the Schur
  172.              form no longer satisfy SELECT=.TRUE.  This could also be caused
  173.              by underflow due to scaling.
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.